.\"
.\" Unixcw CW Tutor Package - cwcp
.\" Copyright (C) 2001-2006  Simon Baldwin (simon_baldwin@yahoo.com)
.\" Copyright (C) 2011-2021  Kamil Ignacak (acerion@wp.pl)
.\"
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License
.\" as published by the Free Software Foundation; either version 2
.\" of the License, or (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write to the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\"
.TH CWCP 1 "CW Tutor Package" "cwcp ver. 3.6.0" \" -*- nroff -*-
.SH NAME
.\"
cwcp \- curses-based Morse tutor program
.\"
.\"
.\"
.SH SYNOPSIS
.\"
.B cwcp
[\-s\ \-\-system=\fISYSTEM\fP]
[\-d\ \-\-device=\fIDEVICE\fP]
[\-w\ \-\-wpm=\fIWPM\fP]
[\-t\ \-\-tone=\fIHZ\fP]
[\-v\ \-\-volume=\fIPERCENT\fP]
[\-g\ \-\-gap=\fIGAP\fP]
[\-k\ \-\-weighting=\fIWEIGHT\fP]
[\-T\ \-\-time=\fITIME\fP]
[\-f, \-\-infile=\fIFILE\fP]
[\-F, \-\-outifile=\fIFILE\fP]
.\"[\-c\ \-\-colours=\fICOLOURSET\fP]
.\".BR
.\"[\-m\ \-\-mono]
.BR
[\-h\ \-\-help]
[\-V\ \-\-version]
.PP
\fBcwcp\fP installed on GNU/Linux systems understands both short form
and long form command line options.  \fBcwcp\fP installed on other
operating systems may understand only the short form options.
.PP
There are no mandatory options.
.PP
Options may be predefined in the environment variable \fBCWCP_OPTIONS\fP.
If defined, these options are used first; command line options take
precedence.
.PP
.\"
.\"
.\"
.SH DESCRIPTION
.\"
.PP
\fBcwcp\fP is a curses-based interactive Morse code tutor program.
It allows menu selection from a number of sending modes, and also permits
character sounding options, such as the tone pitch, and sending
speed, to be varied from the keyboard using a full-screen user
interface.
.PP
.\"
.\"
.\"
.SS COMMAND LINE OPTIONS
.\"
.B cwcp
understands the following command line options.  The long form options
may not be available in non-LINUX versions.
.TP
.I "\-s, \-\-system=SYSTEM"
Specifies the way that \fBcwcp\fP generates tones.  Valid values
are:
\fInull\fP for no tones, just timings,
\fIconsole\fP for tones through the console speaker,
\fIalsa\fP for tones generated through the system sound card using ALSA
sound system,
\fIoss\fP for tones generated through system sound card using OSS sound
system,
\fIpulseaudio\fP for tones generated through system sound card using
PulseAudio sound system,
\fIsoundcard\fP for tones generated through the system sound card, but
without explicit selection of sound system. These values can be
shortened to 'n', 'c', 'a', 'o', 'p', or 's', respectively. The default value
is 'pulseaudio'.
.TP
.I "\-d, \-\-device=DEVICE"
Specifies the device file to open for generating a sound.
\fBcwcp\fP will use default device if none is specified. The default
devices are:
\fI/dev/console\fP for sound produced through console,
\fIdefault\fP for ALSA sound system,
\fI/dev/audio\fP for OSS sound system,
\fIa default device\fP for PulseAudio sound system.
See also \fINOTES ON USING A SOUND CARD\fP below.
.TP
.I "\-w, \-\-wpm=WPM"
Sets the initial sending speed in words per minute.  The value must be
between 4 and 60.  The default value is 12 WPM.
.TP
.I "\-t, \-\-tone=HZ"
Sets the initial sounder pitch in Hz.  This value must be between 0
and 4,000.  A value of 0 selects silent operation, and can be used for
timing checks or other testing.  The default value is 800Hz,
.TP
.I "\-v, \-\-volume=PERCENT"
Sets the initial sending volume, as a percentage of full scale volume.
The value must be between 0 and 100.  The default value is 70 %.
Sound volumes work fully for sound card tones, but \fBcwcp\fP cannot
control the volume of tones from the console speaker.  In this case,
a volume of zero is silent, and all other volume values are simply sounded.
.TP
.I "\-g, \-\-gap=GAP"
Sets the initial extra gap, in dot lengths, between characters
(the 'Farnsworth' delay).  It must be between 0 and 60.  The default
is 0.
.TP
.I "\-k, \-\-weighting=WEIGHT"
Sets the initial weighting, as a percentage of dot lengths.  It must be
between 20 and 80.  The default is 50.
.TP
.I "\-T, \-\-time=TIME"
Sets the initial practice time, in minutes.  \fBcwcp\fP stops after
generating random Morse code for this period.  The value must be
between 1 and 99.  The default is 15 minutes.
.TP
.I "\-f, \-\-infile=FILE"
Specifies a text file that \fBcwcp\fP can read to configure its practice
text.  See \fICREATING CONFIGURATION FILES\fP below.
.TP
.I "\-F, \-\-outfile=FILE"
Specifies a text file to which \fBcwcp\fP should write its current practice
text.
.\".TP
.\".I "\-c, \-\-colours, \-\-colors"
.\"This option specifies an initial colour set for \fBcwcp\fP.  The colour
.\"set is specified as four integers, in the range 0 to 7, separated by
.\".\"commas.  These integers set the display foregrounds, the display
.\"backgrounds, the box foregrounds, and the box backgrounds.  The
.\"available colours are, in order, black, red, green, yellow, blue,
.\"magenta, cyan, and white.  The default colour set is "7,4,7,0".
.\"If \fI\-m\fP or \fI\-\-mono\fP is given, this option is ignored.
.\".TP
.\".I "\-m, \-\-mono"
.\"This option tells \fBcwcp\fP not to attempt to produce a colour
.\"display.  Where colours are not possible, or monochrome
.\"requested, \fBcwcp\fP will use reverse video within its windows to
.\"create its interface.  If this option is given, any \fI\-c\fP
.\"or \fI\-\-colours\fP is ignored.
.TP
.I "\-h, \-\-help"
Prints short help message.
.TP
.I "\-V, \-\-version"
Prints information about program's version, authors and license.
.PP
.\"
.\"
.\"
.SS USER INTERFACE
.\"
\fBcwcp\fP is a curses-based program that takes over the complete
operation of the terminal on which it is run.  If colours are available
on the terminal, it will produce a colour interface.
.PP
The \fBcwcp\fP screen is divided into several distinct areas:
.TP
.I "The Menu Selection window"
The Menu Selection window shows the main modes that \fBcwcp\fP
offers.  Use the \fIF10\fP and \fIF11\fP or \fIKEY_DOWN\fP and \fIKEY_UP\fP
keys to select the mode.  \fIF9\fP or \fIReturn\fP start sending,
and \fIF9\fP again or \fIEsc\fP stop sending.  Changing mode also
stops sending.
.TP
.I "The Morse Code Display window"
This window displays each Morse code character after it has been sent.
.TP
.I "The Speed Control window"
The Speed window shows the current Morse code sending speed in words per
minute.  Pressing the \fIF2\fP or \fIKEY_RIGHT\fP keys increases the speed;
pressing the \fIF1\fP or \fIKEY_LEFT\fP keys decreases the speed.
.TP
.I "The Tone Control window"
This window shows the current Morse code tone pitch.  Use the \fIF4\fP
or \fIKEY_HOME\fP key to increase the pitch, and the \fIF3\fP
or \fIKEY_END\fP key to decrease it.  Values change in steps of 20Hz.
.TP
.I "The Volume Control window"
This window shows the current Morse code volume.  Use the \fIF6\fP
key to increase the volume, and the \fIF5\fP key to decrease it.
Values change in steps of 1%.  Note that \fBcwcp\fP cannot control
the volume of the console speaker, so the volume control only works
effectively for tones generated on the sound card.
.TP
.I "The Gap Control window"
This window shows the current additional 'Farnsworth' gaps to be
appended after each Morse code character is sounded.  Use \fIF8\fP
to increase the gap, and \fIF7\fP to decrease it.
.TP
.I "The Time Control window"
This window shows the selected practice time.  After generating Morse
code in a particular mode for this amount of time, \fBcwcp\fP stops
automatically.  Use \fIKEY_NPAGE\fP to increase the time,
and \fIKEY_PPAGE\fP to decrease it.  During sending, the value in this
window counts down to one, and after final minute of sending has
elapsed, \fBcwcp\fP stops sending.  The timer operates like a microwave
or kitchen timer; it counts down on its own, but the time remaining can
also be altered manually while the timer operates.
.PP
The following keys vary the screen colours:
.TP
.I "{ key"
Changes the foreground colour of the window boxes.
.TP
.I "} key"
Changes the background colour of the window boxes.
.TP
.I "[ key"
Changes the foreground colour of the window contents.
.TP
.I "] key"
Changes the background colour of the window contents.
.PP
Eight screen colours are available for each: black, red, green,
yellow, blue, magenta, cyan, and white.  Use a key to cycle round
these colours for the particular part of the display controlled by
that key.  On a change of colours, the complete screen is repainted.
.PP
Use \fICtrl\-L\fP to repaint the complete screen, in case of screen
corruption.  Use \fICtrl\-V\fP to clear the Morse Code Display Window.
This command is available only when \fBcwcp\fP is not sending.
.PP
To leave \fBcwcp\fP, press \fIF12\fP or \fICtrl-C\fP, or select \fIExit\fP
on the mode menu.
.PP
All of the above command keys may be used while random characters are
being sent, and when keyboard input is being sent.
.PP
If function keys are not available on the terminal, \fICtrl-<key>\fP
combinations can be used.  On the top row of letter keys on the
keyboard, the keys \fICtrl-Q\fP to \fICtrl-I\fP may be used as
alternatives for \fIF1\fP to \fIF8\fP, and on the second row of
letter keys, \fICtrl-A\fP to \fICtrl-F\fP as alternatives for \fIF9\fP
to \fIF12\fP.  For \fIKEY_PPAGE\fP and \fIKEY_NPAGE\fP, use \fICtrl-O\fP
and \fICtrl-P\fP.
.PP
.\"
.\"
.\"
.SS RANDOM CHARACTERS AND WORDS
.\"
.B cwcp
sends random characters in groups of five, with a space between each
group.  After a period of sending, set in
the \fITime Control window\fP, \fBcwcp\fP stops automatically.  It can
also be stopped manually, before this time period expires.
.PP
When sending random words, \fBcwcp\fP sends the complete word, followed
by a space.  Because short words are easier to copy without writing,
\fBcwcp\fP's default dictionary contains only three, four, and five-letter
words in its random words list.
.PP
.B cwcp
chooses at random from a list of around 3000 words in its default
dictionary.  You can change this text using a configuration file, read
at startup.  See \fICREATING CONFIGURATION FILES\fP below.
.PP
.\"
.\"
.\"
.SS NOTES ON USING A SOUND CARD
.\"
By default, \fBcw\fP tries to open default PulseAudio. If PulseAudio
server is not accessible, cw tries to open OSS device "/dev/audio" to access
the system sound card.  This is generally the correct device to use,
but for systems with special requirements, or those with multiple sound
cards, the option \fI-d\fP or \fI\-\-device\fP, combined with
\fI-s\fP or \fI\-\-system\fP can be used to specify the device
and sound system for sound card access.  If the sound card device
cannot be set up, \fBcwcp\fP prints the error message
.IP
cannot set up soundcard sound
.PP
and exits.
.PP
Sound card devices, when opened through OSS sound system, are usually
single-access devices, so that when one process has opened the device,
other processes are prevented from using it. In such cases \fBcwcp\fP
will of course conflict with any other programs that expect exclusive
use of the system sound card (for example, MP3 players).
If \fBcwcp\fP finds that the sound card is already busy, it prints the
error message
.IP
open /dev/audio: Device or resource busy
.PP
and exits.
.PP
.\" The main sound card device will often allow \fBcwcp\fP to control tone
.\" volumes directly, but where this is not possible, \fBcwcp\fP uses the
.\" mixer device instead.  By default, this is "/dev/mixer", but the device
.\" can be specified with the \fI-y\fP or \fI\-\-mdevice\fP options.  In
.\" general, as with the main sound card device, the default mixer device
.\" is usually the correct one to use.
.\" .PP
.\" The mixer device is only used if the sound card does not allow volume
.\" control through the main sound card device.
.PP
The sound card device is not used if \fBcwcp\fP is only sending tones on
the console speaker.
.PP
.\"
.\"
.\"
.SS SOUND OUTPUT \- DEFAULTS AND SELECTION
.\"
\fBcwcp\fP first tries to access sound card using PulseAudio sound system,
using default device name, unless user specifies other sound device with
option \fI-d\fP or \fI\-\-device\fP.
.PP
\fBcwcp\fP then tries to access sound card using OSS sound system
and default OSS sound device name ('/dev/audio'), unless user
specifies other sound device with option \fI-d\fP or \fI\-\-device\fP.
.PP
If opening soundcard through OSS fails, \fBcwcp\fP tries to access
the sound card using ALSA sound system, and default ALSA sound device
name ('default'), unless user specifies other sound device with option
\fI-d\fP or \fI\-\-device\fP.
.PP
If opening soundcard through ALSA also fails, \fBcwcp\fP tries to access
system console buzzer using default buzzer device '/dev/console',
unless user specifies other sound device with option \fI-d\fP or
\fI\-\-device\fP.
.PP
It is very common that in order to access the console buzzer device
user has to have root privileges.  For that reason trying to open
console buzzer almost always fails.  This is not a program's bug,
this is a result of operating system's restrictions.
Making \fBcwcp\fP an suid binary bypasses this restriction.  The program
does not fork() or exec(), so making it suid should be relatively safe.
Note however that this practice is discouraged for security reasons.
.PP
As stated, user can tell \fBcwcp\fP which device to use, using
\fI-d\fP or \fI\-\-device\fP option.  Which device files are suitable
will depend on which operating system is running, which system
user ID runs \fBcwcp\fP, and which user groups user belongs to.
.PP
.\"
.\"
.\"
.SS CREATING CONFIGURATION FILES
.\"
\fBcwcp\fP contains a default set of modes and practice text that should
be enough to begin with.  It can however read in a file at startup that
reconfigures these to provide different character groupings, word sets,
and other practice data.
.PP
To read a configuration file, use the \fI-f\fP or \fI\-\-infile\fP command
line options.  The file should introduce each \fBcwcp\fP mode with a
section header in '[' ... ']' characters, followed by the practice text
for that mode, with elements separated by whitespace.  Lines starting with
a semicolon or hash are treated as comments.  For example
.IP
; Simple example mode
.br
[ A to Z ]
.br
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
.PP
.B cwcp
will generate five character groups for modes whose elements are all single
characters, and treat other modes as having elements that are complete words.
As a starting point for customized modes, \fBcwcp\fP will write its default
configuration to a file if given the undocumented \fI-#\fP option, for
example "cwcp -# /tmp/cwcp.ini".
.\"
.\"
.\"
.SH NOTES
.\"
.B cwcp
owes its existence to the DOS Morse code tutor CP222C.EXE, by VU2ZAP.
CP222C.EXE seemed to offer the right range of facilities for learning
Morse code in a simple, easy-to-use, and compact package.  \fBcwcp\fP
is very much modeled on that DOS program, and should prove useful
both for learning the code, and for experienced CW users who want, or
need, to improve their receiving speed.
.PP
Curses may impose a delay when recognizing the \fIEsc\fP key alone, as
this character is often the first of a sequence generated by a
function key.  \fBcwcp\fP responds instantly to \fIF9\fP.
.PP
The characters echoed in the Morse Code Display window may be ASCII
representations of Morse procedural signals; see the \fBcw\fP(7,LOCAL)
man page for details.
.PP
.\"
.\"
.\"
.SS HINTS ON LEARNING MORSE CODE
.\"
Here are a few hints and tips that may help with the process of
learning Morse code.
.PP
Firstly, do \fBNOT\fP think of the elements as dots and dashes.  Instead,
think of them as dits and dahs (so 'A' is di-dah).  If you think of
them in this way, the process of translating sound into characters
will be learned much more easily.
.PP
Do not learn the characters from a table.  Learn them by watching the
groups appear on the screen, and listening to the sounds produced as
each is sent.  In the very initial stages, it may be beneficial if you
can find a person to take you through the first stages of recognizing
characters.
.PP
Do not waste your time learning Morse code at 5 WPM.  Set the speed to
12 or 15 WPM, but use extra spacing (the Gap window) to reduce the
effective speed to much lower - around four or five WPM \fIeffective\fP
speed.  This way, you will learn the rhythm of the characters as they
are sent, but still have plenty of time between characters.  As you
practice, decrease the gap to zero.
.PP
Learn in stages.  Start by learning the \fIEISH5\fP group, then progress
down through the menu as each group is mastered.  The groups contain
characters which are in some way related, either by sound, or by type
of character.
.PP
.\" \[u0022] = ", otherwise emacs syntax highlighting is messed up;
Once you have completed all the groups \fIEISH5\fP to \fI\[u0022]'$(+:_\fP
(or \fI23789\fP if you do not want to learn procedural signals yet),
use the full character set options, and the words and CW words
options, to sharpen your skill.  If you have difficulties with
particular characters, return to that group and practice again with a
smaller character set.
.PP
Resist the temptation to try to learn or improve your speed by copying
off-air.  You will not know what speed you are working at, and much
hand-sent Morse is not perfectly formed.  What you can gain off-air
though is a general 'resilience', a tolerance for Morse code where
the timing of individual elements, or spacing between characters and
words, is not 100% accurate.
.PP
If working to attain a particular speed for a test, always set the
speed slightly higher.  For example, if aiming for 12 WPM, set the
tutor speed to 14 or 15 WPM.  This way, when you drop back to 12 WPM
you will feel much more relaxed about copying.  Be aware that \fBcwcp\fP
is not necessarily going to send at exactly the speed you set, due
to limitations in what can be done with UNIX timers.  It often sends
at a slower speed than you set, so be very careful with this if you
have a target speed that you need to reach.
.PP
Use the program to make cassette tapes that you can take with you in a
walkman or in the car, for long journeys.  You do not have to write
down everything you hear to practice Morse code.  Simply listening to
the shapes of characters over a period will help to train your brain
into effortless recognition.  In fact, slavishly writing everything
down becomes a barrier at speeds of 15-20 WPM and above, so if you can
begin to copy without writing each character down, you will find
progress much easier above these speeds.  But do not over-use these
tapes, otherwise you will quickly memorize them.  Re-record them with
new contents at very regular intervals.
.PP
Try to spend at least 15-30 minutes each day practicing.  Much less
than this will make progress glacially slow.  But significantly more
than an hour or so may just result in you becoming tired, but not
improving.  Recognize when it is time to stop for the day.
.PP
Do not worry if you reach a speed 'plateau'.  This is common, and you
will soon pass it with a little perseverance.
.PP
At higher speeds, CW operators tend to recognize the 'shape' of whole
words, rather than the individual characters within the words.  The CW
words menu option can be used to help to practice and develop this
skill.
.PP
.\"
.\"
.\"
.SH ERRORS AND OMISSIONS
.\"
The calibration option is a bit ropy.  It simply sends PARIS
repeatedly, and relies on you to time the sending and then work out if
any adjustment to the speed is really necessary.  Automatic
calibration by making measurements over a given period would be a lot
better.
.PP
Generating random CW QSOs would be fun to do.
.PP
A facility to allow a user to key Morse into the system, and to have
it send code, and measure the accuracy of keying, would be nice.
.PP
.\"
.\"
.\"
.SH SEE ALSO
.\"
Man pages for \fBcw\fP(7,LOCAL), \fBlibcw\fP(3,LOCAL), \fBcw\fP(1,LOCAL),
\fBcwgen\fP(1,LOCAL), and \fBxcwcp\fP(1,LOCAL).
.\"
